The Atari Compendium

home *** CD-ROM | disk | FTP | other *** search

/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / utils / egale21e.lzh / EGALE.E / EGALE.TXT < prev next >

Wrap

Text File | 1994-11-09 | 83KB | 2,068 lines

¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ The tool for easy file comparisons, alteration and analysis © 1993,94 by David Reitter Égale is Shareware and may be copied unchanged. ______________________________________________________________________________ Version 2.1i, dated 1st November 1994 ============================================================================== Manual ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ ***** Contents 1. Introduction 1.1 What's Égale for? 1.2 Features 1.3 Distribution and your Shareware obligations 1.3.1 Updates 1.3.2 Égale UK Support and Registration 1.3.3 Égale registration outside the UK 1.4 Égale origins 1.5 User interface 1.5.1 Using dialogs 1.5.2 Pop-up menus 1.5.3 Keyboard shortcuts 2. 'File' drop down menu 2.1 Open... 2.2 Open binary... 2.3 Close 2.4 Discard 2.5 Save as... 2.6 Create list... 2.6.1 Why use a patch program? 2.6.2 How to create a patch program 2.6.3 How to use a patch program 2.6.2 How to create a patch program 2.6.3 How to use a patch program 2.6.3 How to use a patch program 2.7 Information... 2.8 Quit 3. 'Find' drop down menu 3.1 Find... 3.1.1 'Find' examples 3.2 Find next 3.3 Jump... 3.3.1 Jump into action 3.4 Line equalisation... 3.4.1 Equalise: A step by step tutorial 3.5 - Automatic... 3.6 First difference OR First identical line 3.7 Next difference OR Next identical line 4. 'Edit' drop down menu 4.1 Undo 4.2 Insert text line... 4.3 Edit text line... 4.4 Insert line 4.5 Delete line 4.6 Load status log... 4.7 Save status... 4.8 Clear status... 5. 'Window' drop down menu 5.1 Cycle 5.2 Help 5.3 Files 6. 'Options' drop down menu 6.1 Comparison mode... 6.2 Number lines 6.3 Emphasis... 6.4 Display... 6.5 Fonts... 6.6 Colours... 6.7 Save settings... 6.8 Load saved settings... 6.9 Quick save and exit 7. Other functions 9.1 Display functions 9.2 Single line comparison using one-line windows 9.3 Moving files 8. Advanced Égale features 8.1 Passing parameters 8.2 Passing parameters using EGALEPAR.PRG 9. Technical notes 9.1 Protocols supported 9.2 Known bugs 9.3 Hints & tips 10. Miscellaneous 10.1 Credits 10.2 Warranty and liability Hinweis: Es gibt eine deutschsprachige Version. ____________________________________________________________________________ *****1. Introduction 1.1 What's Égale for? Here's a few examples: Two identical filenames on different disks, same filesize, same datestamp but are they really exactly the same? When Égale loads two identical files a dialog is displayed confirming they are identical, and you can either select other files, exit or continue and display the files. You update a program or document, then decide some of the changes you've made are a backward step, and would like to review all the changes made since you last saved a back-up. Load the current and back-up files into Égale and the differences between the two files will be highlighted. You can save the differences as a file and review these as desired. You discover a minor but nasty bug in a program you've already released! Load the original and updated executable files into Égale and after following a simple procedure Égale will generate a compact patch program which you can release to your users. Égale provides a solution for everyone who has been confronted with these or similar problems. Égale is useful to anyone who needs to compare or 'hack' files, programmers, journalists, etc. In principle these tasks could be performed using a text editor or other application but Égale (as far as we are aware) is the only custom application designed to manage these tasks which it does with the minimum of fuss via an enhanced GEM interface. Save your brain, let Égale take the strain! 1.2 Features - Two files are loaded in each window and displayed side by side, adjacent to one another, with the window divided vertically. - Égale can also load a single file so that you can analyse its format or amend it. This feature turns Égale into a binary editor for patches and similar applications. - Any file size up to the limit imposed by the available working memory in your machine can be loaded... - Compare both text and binary files. - Delete individual lines or characters or insert dummy (blank) lines between them. - Various features available to assist in locating differences: + Individual lines can be displayed one above the other in an extra one-line window to make visual comparison easier. + Can locate inserted and deleted parts of a file in comparison with another file automatically. + Line numbering, optional. + Comparison of characters OR by interpreting each line as a numerical value (handy for adjusting spreadsheet data). The numerical value can be asigned a 'tolerance'. Any value which falls within the defined tolerance range are considered equal by Égale. + Status log/Diff file (containing the position of inserted and deleted lines) can be saved and loaded. + Wildcard search function. + Jump (Goto) to any desired line number, relative to the current line or from the start line (absolute). - Loaded files can be exported directly to an editor of your choice for further processing. - Vertical divider bar separating two files in each window can be freely positioned. - [Help] key displays keyboard shortcuts, and context-sensitive help in dialogs if ST-Guide or other hypertext system is installed. - Enhanced GEM interface, runs on ST, TT and Falcon030 computers. Supports multitasking systems under TOS at all screen resolutions from 640x200 pixels (ST medium) upwards. + There are minor problems with the display of small text at 640x200 so a seperate RSC file EGALEMID.RSC is provided. To use this rename the existing EGALE.RSC file to EGALE.RSH, then EGALEMID.RSC to EGALE.RSC. Remember to reverse the process when you want to run at higher resolutions or Égale will behave strangely! 1.3 Distribution and your Shareware obligations Distribution of Égale is encouraged for non-commercial purposes. PD and Shareware libraries may also distribute Égale so long as I am informed in writing. The following files comprise Égale and must be distributed together and intact: EGALE.PRG Égale executable EGALE.RSC RSC file for all resolutions above 600x200 EGALEMID.RSC RSC file for 600x200 (ST Medium resolution); rename EGALE.RSC to EGALE.RSH then rename EGALEMID.RSC to EGALE.RSC when you want to run Égale in ST Medium rez. EGALE.DOC This documentation Égale may only be included on magazine cover disks, CD-ROM or other compilations with the author's prior written permission. Any contravention of my wishes is a breach of Copyright and this Shareware statement and will be strongly challenged! Égale is Shareware. The current UK Shareware fee is £10.00 and if you use Égale regularly your obligations under Copyright law are clear. After a short evaluation period, either register your copy or stop using Égale. The future development of Égale depends largely on the support from you. Although the unregistered version of Égale is perfectly usable the benefits of registration are considerable: o Option to compare files for similarities as well as differences. o One can save parts of the files. o One can create lists of differences or similarities. o One can create patch programs which can be used to alter a source file to correspond with a (so-called) target file. o Instead of simply toggling the Emphasis option on/off a dialog appears from which the following extra options are available: Use colours, Bold, Hide the rest, Divider only, Mark each character, First target, All and Inserts. o Automatic line equalisation is available for whole files. o The form of the line-cursor can be changed to give a clearer display under some conditions. o Pop-up menu offers extra options to make tab characters in text visible in different ways and to vary the width of tab stops. o Another pop-up menu in 'Display...' allows one to view the displayed files subdivided with faint horizontal lines. Égale can draw thin graphic lines at 2 or 4 line intervals which is particularly useful in binary mode to indicate word or longword boundaries. o An Info line provides information about the line at the cursor. o Registered users will get a printed quick-reference summary giving an overview of the functions and options offered. (If registered via Joe Connor) o Access to the UK Update and support service. 1.3.1 Updates You can get the actual version of Égale - at the KGB Wiesbaden Mailbox: Call +49-611-375201, log in as "EGALE", password "EGALE". You will be asked which version (International English language version or the German one) you'd like to get. The BBS will transmit Égale using the Z-Modem protocol. - from Joe Connor (see 'Égale UK Support and Registration') - from David Reitter (see 'Égale registration outside the UK') 1.3.2 Égale UK Support and Registration On registration you will receive a 'Key' to 'unlock' the Registered user only features. To register your copy of Égale in the UK follow the procedure below: a) Make a cheque for £10.00 payable to Joe Connor b) Be sure to include your surname, forename and full address. The Égale 'Registration dialog' offers a convienent method of ordering your key with the added benefit of checking the format of your details. Enter your details and press [Alternate]+[R] or click on the 'Order' button. After validating your details a further dialog appears from which you can output the letter either directly to the printer or to a file for further processing, for example to send as Email. c) Send letter and cheque to the UK Address below: Joe Connor 65 Mill Road Colchester CO4 5LJ England Email: jconnor@cix.compulink.co.uk Update service Registered UK users can obtain the latest English Version from Joe Connor at any time, free of charge until otherwise notified, by sending a Stamped Addressed Envelope enclosing a floppy disk - so long as the latest version has not become commercial. Installing your Key Enter your key details into the registration dialog and press [Return] twice to clear the dialogs, then select 'Save default settings' from the 'Options' menu to save the registration details (in EGALE.INF). So long as you don't delete your copy of EGALE.INF and I don't change the format you won't be troubled by the registration procedure in future Égale updates. Remember Égale uses the EGALE.INF file to store your personal preferences and key so be sure to delete EGALE.INF before passing copies of Égale on to friends or other users. 1.3.3 Égale registration outside the UK You can either register as detailed in Égale UK Support and Registration above or as follows: 1) By Email If you have a modem and access to the Maus net send your details to the following address: From inside the Maus net: David Reitter @ WI2 Via the Internet: david_reitter@wi2.maus.de Transfer 20.- DM to me. Here's my Bank details: David Reitter KTO (Account No.): 0229 773 BLZ (Sort code) : 550 700 40 Deutsche Bank Mainz A suitable key will be returned by Email. 2) By post Send me: A 20.- DM note together with your registration details, a self addressed envelope (or label) and 2 International Reply Coupons. Your key will follow by return of post. Important! o If anything is missing, nothing will come back, you have been warned! o Those that register agree that their data may be stored in electronic form on a computer. o Registered users will get a printed quick-reference summary giving an overview of the functions and options offered (only if registered via Joe Connor!). They can also send me a formatted disk, a self-addressed envelope and two International Reply Coupons at any time to receive the latest version of Égale, as long as this version is not being distributed commercially, or may, if they wish and have a modem, obtain the latest beta-test version from the Wiesbaden Mailbox. o Unregistered users can obtain a new version from me (once only) by post. David Reitter Albinistr. 10 D-55116 Mainz Germany 1.4 Égale origins Égale was originated by Christof Schardt. At that time the program was still called COMPARE and did not use GEM, so ran only in ST high resolution. At the start of 1993 COMPARE was completely re-programmed and incorporated the usage of GEM. It's now called 'Égale'. Why 'Égale'? 'égal' in French means 'equal', 'égale' is the feminine form. And why should all programs bear some sort of English name?! We've graciously ignored the fact that one doesn't use accents with (French) capital letters ! ..The programmer:................... : : : David Reitter : : Albinistr. 10 : : 55116 Mainz : : Germany : : Tel.: +49 6131 233255 : : Email: david_reitter@wi2.maus.de : :..................................: 1.5 User interface Thanks to its GEM operation the usage of Égale is largely self-explanatory. That makes it that much harder to explain everything in these instructions in a way that is easily understood. Instead of listing all the menu points these instructions are divided into sections related by meaning. Égale uses all the popular features of the enhanced GEM interface. Most of these features are now in common usage in other software. Here's an overview: 1.5.1 Using dialogs Égale dialogs can be displayed in windows. The following features are available: - Selectable objects include an underlined character. - The 'Cancel' button in dialogs and alert boxes can be selected by pressing the [Undo] key. - The 'Asses ear' at the top right of most dialog boxes can be used to move dialog boxes around the screen. A click and drag operation is used; during flight dialogs become invisible. 1.5.2 Pop-up menus Each bold dialog option button contains a pop-up menu. Click on the button to display all the menu options or click on the circular arrow box to cycle through the available options. Further options can be selected using either the mouse or keyboard. Click on an option using the mouse to select it or click away from the pop-up menu to close without making a selection. The following keyboard commands are active within pop-up menus: Key Action ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ [Up-arrow] Move selection bar up. [Down-arrow] Move selection bar down. [Return] Select entry. [Undo] Exit pop-up without selection. [Esc] Exit pop-up without selection. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ 1.5.3 Keyboard shortcuts 'Within this document square brackets' '[...]' ' are used to denote keys on the keyboard.' The [Shift] keys within Égale are 'NOT' interchangeable. Use the left [Shift] key for the left part of a divided window and the right [Shift] key for the right part of the window; logical, eh? Keyboard shortcuts are listed next to each menu entry. Here are the details: (Top hat).......................... '^' = [Control] key. (Up-arrow)......................... ' ' = [Shift] key. (Looks like Window fuller icon).... ' ' = [Alternate] key. Keyboard control ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ [Left-arrow] Window scrolls 5 characters left. [Right-arrow] Window scrolls 5 characters right. [Up-arrow] Marker moves 1 line up, window scrolls if at edge. [Down-arrow] Marker moves 1 line down, window scrolls if at edge. [Shift]+[Left-arrow] Window scrolls 1 character left. [Shift]+[Right-arrow] Window scrolls 1 character right. [Shift]+[Up-arrow] Window scrolls 1 screen page up. [Shift]+[Down-arrow] Window scrolls 1 screen page down. [ClrHome] Marker positioned on first line. [Shift]+[ClrHome] Marker positioned on last line. ____________________________________________________________________________ *****2. 'File' drop down menu 2.1 Open... Select this option to load and display files in text mode. Unless Égale is passed file/s as parameters, e.g. from a command line, the file selector appears in which one or two files must be selected in turn followed by 'OK.' If the first selected file is executable (ACC, APP, PRG, TOS or TTP) a dialog appears asking whether the file should be loaded in binary mode. If you select 'Cancel' in the second file selector, i.e. specify only one file, then Égale will only load a single file. This can be useful for analysing file formats, as well as for editing (binary) files. Wildcards are allowed in the file selector, for example: FILE?.TXT would load the first two matching files - if you had a series of files FILE1.TXT, FILE2.TXT, FILE3.TXT ... then FILE1.TXT and FILE2.TXT would be loaded. If two matching files are found they're loaded and the second file selector isn't displayed. If you're using Selectric™ and you select more than two matching files the first two matches are loaded. If there's not enough memory to load files, they can be compared. The position of the first difference is displayed. If one is loading in text file mode (i.e. 'Open binary...' has not been used) and the file being loaded contains ASCII 0 (NULL) characters, then these have to be converted. Égale will ask you to what character they should be converted: - 'SPACE' (Space character ' ', ASCII 32) - 'ø' (ASCII 179) - 'TAB' (Tabulator 'clock' character, ASCII 9) Then the files will be loaded and displayed in a newly opened single GEM window. All the 'gadgets' and scroll bars behave normally. 2.2 Open binary... Select this option to load and display files in binary mode. Unless Égale is passed file/s as parameters, e.g. from a command line, the file selector appears in which one or two files must be selected in turn followed by 'OK.' In binary mode only one byte per line is displayed on screen. Each byte is displayed in hex, decimal, binary and ASCII format. Some functions are unavailable (greyed out) in binary mode. Otherwise the loading of binary files proceeds in the same way as for loading text files. 2.3 Close Selecting 'Close' or clicking on the 'close' icon (top left hand corner) closes the window but holds the files in memory, which means it may be re-opened by clicking on one of the entries in the 'Window' menu, or pressing [Alternate]+ corresponding number. 2.4 Discard One-line window/s can be discarded by clicking on their 'close' icon or, if you are closing the file window which called them, by clicking on the 'close' icon of that file window. File windows must be discarded (rather than closed) to remove them from memory, which may be neccessary if you're running short of memory. 2.5 Save as... Select this option to save a file to disk. Enter or select a filename using the file selector then select 'OK'. The file is stored in the original format. Insertions are stored as a blank line or (in binary mode) as a NUL byte (ASCII 0). 2.6 Create list... Select this option to display the 'Output' dialog. The following options are available: Save part of the file Select this option to save any parts of a file. Having selected 'Save part of the file' , you can setup the following options: 'File:' Select which file is to be saved. The filenames of the file(s) in the topped window are displayed. If you have loaded two files you can toggle between them. A round filled button shows the selected file. 'As bytes list:' [Alternate]+[B] --* Binary files ONLY *-- A check box offers a choice between: 'Unchecked:' Default. Binary file saved in the same format as loaded, thus an executable file remains executable. 'Checked:' File saved as character list (as displayed in the file window) with hex, decimal, binary and ASCII columns. Optionally, only if this box is checked, line numbers can also be saved and the 'Print' button is available. 'Number lines:' [Alternate]+[N] This option is not available (greyed out) if a binary file is selected in binary format. A check box offers a choice between: 'Unchecked:' Default. Line numbers are not saved with the file. 'Checked:' Line numbers are saved with the file. 'Insertions and deletions:' 'Omit insertions:' [Alternate]+[I] A check box offers a choice between: 'Unchecked:' Default. Insertions made with the 'Insert text line...' function are saved with the file. 'Checked:' Insertions are not saved with the file. 'Text:' An editable text field (22 characters max) enable a text string to be written to the file in place of the inserted lines. If this field is empty (by default this field contains '-') a blank line is written. 'Write deletions:' [Alternate]+[W] A check box offers a choice between: 'Unchecked:' Default. Deleted lines are not saved to the file. 'Checked:' Deleted lines are saved to the file (losing your changes!). The defaults are set to save all the changes you make to a file. 'What?:' It's easier to handle the 'From line:' and 'to:' options if the 'Number lines' option from the 'Options' menu is turned on. 'From line:' (Default '1') Select the first line to be saved. 'to:' (Defaults to last line of file) Select the last line to be saved. 'Only different ones' OR 'Only identical ones:' [Alternate]+[Y] A check box offers a choice between: 'Unchecked:' Default. All lines between the 'From line:' and 'to:' options are saved to the file. 'Checked:' All differing OR matching lines, depending on the 'Search for' setting in the 'Comparison mode' dialog, between the 'From line:' and 'to:' options are saved to the file. Hints & tips The option to save only the different (or identical) lines, used together with line numbering, makes it easy to keep track of the changes between files. 'Print:' [Alternate]+[P] This button outputs the selected data to the printer. This option is not available (greyed out) if a binary file is selected in binary format. --> Unregistered? The 'Save file' function is not available in the unregistered version. List of differences/correspondences A list of difference/correspondences, depending on the 'Search for' setting in the 'Comparison mode' dialog, can be saved or printed in 'xx/yy' format. Example: ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ Differences between D:\EGALE\EXAMPLE5.TXT / D:\EGALE\EXAMPLE6.TXT 7/7 15/15 e--/16 25/26 30/31 e55/-- 79/79 .../ ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ The file 'EXAMPLE5.TXT' has differences in lines 7, 15, 25, 30 and 79 compared to the second file. The corresponding line number in 'EXAMPLE6.TXT' is also indicated (after the '/'). Inserted lines are indicated by a broken line ('--') and an 'i' is placed at the start of the line; deleted lines are not mentioned! The '...' dots at the end indicates the two files (including any insertions and deletions already made) have a different length. If the dots are to the left of the '/' there are more lines in the left hand file and vice versa. 'With relevant lines: ' [Alternate]+[W] A check box offers a choice between: 'Unchecked:' Default. The contents of the corresponding lines/characters are not saved to the list. 'Checked:' The contents of the corresponding lines/characters are included below (with text files) or next to (with binary files) the usual list data, described above. --> Unregistered? The 'List of differences' function is not available in the unregistered version. Patch program It's possible to create an executable program (PRG) which can be used to alter a source file to correspond with a (so-called) target file. This is commonly referred to as a 'Patch program' and is used to update minor differences between files. The 'Print' button is not available (greyed out) if patch program option is selected. 2.6.1 Why use a patch program? Patch programs evolved mainly for the benefit of on-line users where every byte costs money to transmit. They're commonly used to update executables but can also be used to update documentation. Let's suppose you've just released a 200kb masterpiece for beta testing and after a number of minor bugs have been reported you want to release a fixed version. What are your options? - Send each beta tester a new file? Expensive and time consuming... - Send each beta tester a list which they can use to manually patch their copy using a hex-editor? Error prone and awkward... - Send them a small patch program which automatically updates their copy? 2.6.2 How to create a patch program 1) Load the 'BUGGED.PRG' followed by 'NEW.PRG' into Égale. 2) Ensure that 'Chap.numbers' (leading numbers) in the 'Ignore' area of the 'Comparison mode' dialog from the 'Options' menu is cleared otherwise Égale will not be able to recognise the relevant lines as different. 3) Equalise the files using either manual or automatic line equalisation. 4) Select 'Create List...' from the 'File' menu to display the patch dialog. 5) Select the 'Patch BUGGED.PRG to NEW.PRG' option, then 'OK.' 6) The file selector appears; enter a filename for the patch program, e.g. 'PATCH.PRG' followed by 'OK.' 7) Égale compares the two files line by line or byte by byte and creates an executable 'PATCH.PRG' which does the following: - An inserted line in the source file will be added to the target file. - A deleted line in source file will be deleted in the target file. - Any differing lines will be replaced in the target file with the contents of the source file. It's important to check the patch program worked correctly and the easiest way to do this is to load the file generated by the patch program and compare it with your updated master. If they are 'equal' everything worked! The size of the patch program depends on two main factors: - The number of changes made to the source file. The more changes, the bigger the patch program (from an initial overhead of ~12kb). If there are too many changes the patch program can easily grow larger than the source program, which completely defeats the object! - The line length. Replacing long line/s dramatically increases the size of the patch program. 2.6.3 How to use a patch program 1) Run PATCH.PRG and the file selector appears usually displaying the file it's looking for. 2) Load in 'BUGGED.PRG' followed by 'OK.' 3) The patch program checks whether it's the file it's looking for then re-displays the file selector. 4) Enter the filename for the output program 'NEW.PRG' followed by 'OK.' 5) The patch program generates 'NEW.PRG'. 2.6.2 How to create a patch program 1) Load the 'BUGGED.PRG' followed by 'NEW.PRG' into Égale. 2) Ensure that 'Chap.numbers' (leading numbers) in the 'Ignore' area of the 'Comparison mode' dialog from the 'Options' menu is cleared otherwise Égale will not be able to recognise the relevant lines as different. 3) Equalise the files using either manual or automatic line equalisation. 4) Select 'Create List...' from the 'File' menu to display the patch dialog. 5) Select the 'Patch BUGGED.PRG to NEW.PRG' option, then 'OK.' 6) The file selector appears; enter a filename for the patch program, e.g. 'PATCH.PRG' followed by 'OK.' 7) Égale compares the two files line by line or byte by byte and creates an executable 'PATCH.PRG' which does the following: - An inserted line in the source file will be added to the target file. - A deleted line in source file will be deleted in the target file. - Any differing lines will be replaced in the target file with the contents of the source file. It's important to check the patch program worked correctly and the easiest way to do this is to load the file generated by the patch program and compare it with your updated master. If they are 'equal' everything worked! The size of the patch program depends on two main factors: - The number of changes made to the source file. The more changes, the bigger the patch program (from an initial overhead of ~12kb). If there are too many changes the patch program can easily grow larger than the source program, which completely defeats the object! - The line length. Replacing long line/s dramatically increases the size of the patch program. 2.6.3 How to use a patch program 1) Run PATCH.PRG and the file selector appears usually displaying the file it's looking for. 2) Load in 'BUGGED.PRG' followed by 'OK.' 3) The patch program checks whether it's the file it's looking for then re-displays the file selector. 4) Enter the filename for the output program 'NEW.PRG' followed by 'OK.' 5) The patch program generates 'NEW.PRG'. 2.6.3 How to use a patch program 1) Run PATCH.PRG and the file selector appears usually displaying the file it's looking for. 2) Load in 'BUGGED.PRG' followed by 'OK.' 3) The patch program checks whether it's the file it's looking for then re-displays the file selector. 4) Enter the filename for the output program 'NEW.PRG' followed by 'OK.' 5) The patch program generates 'NEW.PRG'. --> Unregistered? The 'Patch program' function is not available in the unregistered version. 2.7 Information... Select this option to display the 'Information...' dialog. The following information about each file in the topped window is displayed: 'File names: Filename1 Filename2 'No. of lines: x y 'Differing lines: x y 'Average line length: x y 'Size (Bytes): x y 'Inserted/deleted: x y 'Maximum possible: 1000 1000' (default) A further button 'General Info' [Alternate]+[G] can be used to display a further 'General information' dialog. This dialog appears immediately if file window is open. The following information is displayed: 'Open/maximum windows: x/y 'Open/maximum files: x/y 'Lines per file: Unlimited 'Available memory:' The largest contiguous block is displayed in Bytes. 2.8 Quit Select this option to leave Égale; any changes to files and settings are 'NOT' stored using this option. ____________________________________________________________________________ *****3. 'Find' drop down menu 3.1 Find... Select this option to display the 'Find' dialog. The following options are available: 'In:' If two files have been loaded in the topped window, both filenames are displayed along with a check box for each filename. By default both files will be searched (i.e. both check boxes are crossed). To restrict the search to either file de-select the other file (i.e. clear its check box). 'Input as ASCII value:' [Alternate]+[V] A check box offers an option to search for the ASCII value equivalent(s) of the actual string displayed in the editable 'Text:' field. 'Text:' Enter the desired search string into the editable field. In addition to searching for normal text strings Égale can search for ASCII values if the 'Input as ASCII value' option is active (checked). Enter the numbers in the following format: Decimal: Enter the number e.g. 144 for 'É'. Hexadecimal: Precede the number with a '$' e.g $90 for 'É'. Octal: Precede the number with a '&O' e.g &O220 for 'É'. * * The 'O' is capital O, NOT 0 (zero). 'Options:' 'Caps/l.c. sensitive:' [Alternate]+[L] A check box offers the choice between: 'Unchecked:' Default. The search is not case sensitive, i.e 'e'='E'. 'Checked:' The search is case sensitive, i.e 'e' is not equal to 'E'. 'Wildcards:' [Alternate]+[W] These are commonly found in other programs and have become standardised across different computer platforms as follows: '*' represents any text string (the string may even be empty). '?' represents any single character. A check box offers a choice between: 'Unchecked:' (Default) Wildcards are treated as normal characters 'Checked:' Wildcards '?' and '*' are active. 'Character tolerance:' Greyed out and not currently implemented. After a successful search Égale always displays the found string in the visible part of the window, scrolling the line horizontally if necessary. The found string is pinpointed by a brief growing and shrinking rectangle centred on it and the line cursor covering just the found area. If a search string is found in the same line in both files in the window then that in the left file will be highlighted. With the 'Find next' menu entry or [Control]+[G] you jump to the next occurrence of the search string in the text (if any). 3.1.1 'Find' examples Search string... finds... but not... ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ m?le mile, mole mill, mere m??l meal, mill motel vine* vine, vineyard vein large *room large diningroom large kitchen large bedroom smallest room Important! Matching strings which wrap around more than one line will also be found and the cursor positioned on the first line. Example: Search string... finds... and... ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ fly*fish flying fish fly down to Florida to catch some fish 3.2 Find next Select this option to continue to search the files using the current search string from the current cursor location. 3.3 Jump... Select this option to display the 'Jump' dialog. The following options are available: 'Absolute:' [Alternate]+[B] The line number counted from the first line of the file is jumped to. 'Relative:' [Alternate]+[R] The line separated from the current line by the entered number is jumped to. Negative values can also be entered to jump backwards through files. You can toggle between these two options. A round filled button shows the active mode. 'In:' If two files have been loaded both filenames of the topped window are displayed along with the default 'To position in window' option. You can toggle between these three options. A round filled button shows the active mode. 'To position in window:' [Alternate]+[P] Égale takes account of any inserted and deleted line and jumps the specified number of lines to the position that would be reached by moving the line cursor the corresponding number of times within the file window. If either filename is selected the jump is to the specified line number and any lines inserted or deleted are not taken account of. 3.3.1 Jump into action Take a look at our imaginary file and notice the dummy line inserted between lines 2 and 3 and the two dummy lines inserted between 4 and 5. Let's consider the 4 different possibilities of jumping 3 lines forwards: 1 This is line one 2 This is line two (b) -------------------- (a) 3 This is line three ---> 4 This is line four <--- Line cursor starting position -------------------- -------------------- (c) 5 This is line five 6 This is line six (d) 7 This is line seven Absolute/Relative Either filename/Position in window Final position ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ Checked............................Checked............ (b) .........Checked...................Checked............ (c) .........Checked.. Checked............................ (d) 3.4 Line equalisation... Equalisation is used to align, as far as possible, two basically similar files. This is achieved by inserting dummy lines into either file to match up identical areas in the files. Equalisation can quickly isolate changes in documentation and executables but only makes sense if the two files are basically similar. Equalising two completely different or identical files is pointless! Consider the two files shown below which represent two basically similar files. Before equalisation Égale recognises lines 1 and 2 as identical but because line 3 differs, due to 'Insertion A', the rest of the file is considered different. Using equalisation we can instruct Égale to insert dummy lines into the left hand file and progressively match up (or equalise) the two files. Example: EXAMPLE1.TXT EXAMPLE2.TXT ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ Line 2 Text 2 Text 2 Line 3 Text 3 Insertion A Line 4 Text 4 Text 3 Line 5 Text 5 Text 4 Line 6 Text 6 Insertion B Line 7 Text 7 Insertion C Line 8 Text 5 Line 9 Text 6 Line 10 Text 7 3.4.1 Equalise: A step by step tutorial Run Égale and load in the demo files 'EXAMPLE1.TXT' and 'EXAMPLE2.TXT' and your screen should appear similar to that in 'Line equalisation...' above. Select: Number lines entry from the 'Options' menu. Result: Lines are numbered. Help: So you can follow the steps more easily! Action: Use [Down-arrow] to move line cursor to line 3. Help: There's no point equalising line 1 and 2 because Égale already indicates they are identical. Attempting to equalise an identical line displays an alert box with the following message: 'Both adjacent lines are identical.' Select: ' Line equalisation...' from the 'Options' menu. Result: Dialog asks: 'Search for left or right line on opposite side?' Help: In our example we want to search for the left hand text on Line 3 in the file on the right hand side, so... Select: 'Left' Result: Égale searches the right hand file for a matching line and if found the 'Line equalisation' dialog appears, otherwise the the system bell is sounded. Help: If a match is found the following information is displayed: The number of matching lines and the location of first matching line relative to the current line; for our example this is: '2 equal lines found 1 line away' This information gives us a good clue as to whether there might be a better match elsewhere in the file; usually a large number of matching lines indicates a good fit. A single line match, particularly when comparing binary files, is unreliable because any single character is likely to be repeated many times in a single file. Four options are available; select the 'Always' option to complete the tutorial: Option: 'OK' [Return] or [Enter] (default). Result: Égale equalises the line and exits the dialog. The file window is updated with the addition of the dummy line and the first 5 lines in the file window are shown as aligned. Option: 'Always' [Alternate]+[W] Result: Same as for 'OK' plus: The 'Line equalisation' dialog will not appear during subsequent equalisations until either [Control] or [Alternate] are held down whilst selecting 'Line equalisation...' Note: If manual equalisation is called using [Control]+[K] you have to keep the [Control] key pressed during the 'Left/Right/Cancel' dialog selection. Help: Because the 'Always' option doesn't display the 'Line equalisation' dialog no information about the match is displayed, so you run the risk of matching the wrong lines as mentioned earlier! Option: 'Continue' [Alternate]+[T] Result: XX Option: 'Cancel' [Alternate]+[C] Result: The 'Line equalisation' dialog is exited without making changes. Select: 'Next difference' [Control]+[N] The line cursor moves to line 5. Select: 'Line equalisation...' from 'Options' menu. Result: Dialog asks: 'Search for left or right line on opposite side?' Select: 'Left' again. Result: Two dummy lines are inserted between lines 4 and 5 and the file window is updated with all lines equalised. Alternatively individual lines can be equalised by right mouse clicking on the left file to search for a match in the right hand file and vice versa. This avoids the 'Left/Right/Cancel' dialog. The 'Line equalisation' dialog appears as before offering the same options. 3.5 - Automatic... Select this option to display the 'Automatic line equalisation' dialog. Égale attempts to equalise the two files by inserting dummy lines into both the left and right parts of the window where neccessary to align the files. This is similar to a series of manual line equalisations except both files are equalised in a single operation. If you're not sure which parameters to use select the 'Default' button to restore the default settings which are suitable for most situations. The following options offer a degree of control over how lines are equalised: 'How many lines are needed for recognition after a 'gap'?' ' (Default '1'). Sets the minimum number of matching lines which must be found in the opposite file before Égale recognises the 'gap' as an insertion. Consider the following example: EXAMPLE3.TXT EXAMPLE4.TXT Comments ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ Text B Text B lines match... Text C Some text Text D inserted Text E Text C -> Two consecutive * Text F Text D -> matching lines * Text G Gap text Text H Text E -> Only one matching line here # Text I Gap text If the 'gap' value is set to 1 both * and # would be equalised. If the 'gap' value is set to 2 * would be equalised, but not #. If the 'gap' value is set to 3 (or more) neither * nor # would be equalised. 'How many characters/line (min)?' (Default '1') --* Text files ONLY *-- The purpose of this option is to ensure that during equalising of blank lines blank lines are not inserted (although dummy lines can be inserted opposite blank lines). The only time it's worth changing the default option is when a text file contains hardly any blank lines, in which case change this setting to '0.' 'What is the maximum number of lines for a 'gap'? ' To ensure equalisation set this value just larger than the largest number of lines inserted into either file. For example if one of the files has had several lengthy paragraphs, each less than 50 lines, inserted then '50' lines will be sufficient. On the other hand if one paragraph of 150 lines has been inserted you'll need to up the value to at least this figure to equalise the files. In the example above: If the value is set to '1' then * would not be equalised but # would. If the value is set to '2' (or more) both * and # would be equalised. Lines can also be inserted manually in the appropriate file by pressing: [Insert]+[Left Shift] to add a line to the left hand file. [Insert]+[Right Shift] to add a line to the right hand file. 'Start at:' 'Beginning:' [Alternate]+[B] Search begins at the start of the files. 'Cursor position:' [Alternate]+[P] Search begins from the current position. You can toggle between these two options. A round filled button shows the active mode. 'Keywords:' Use this option to equalise files which contain frequently repeated keywords at the start of lines. A check box offers a choice between: 'Unchecked:' Default: Keywords are ignored 'Checked:' The file selector appears prior to equalisation from which you can select a previously prepared ASCII file of keywords. If a keyword is encountered during equalisation and no corresponding line exists in the opposite file, the opposite file will be equalised by inserting line/s. All other lines are NOT equalised. This option is handy for aligning source code, especially if normal equalisation doesn't yield sensible results. Example keyword file For GFA Basic source code in LST format a simple two line file: PROCEDURE FUNCTION should be suitable. Create a file containing the two lines above and save them in ASCII format. Something similar should be possible for Pascal or Modula-2. Some assemblers even support '>PART' in their display, which aids equalisation. Égale uses an intelligent algorithm for automatic equalisation and equalises most files efficiently. The algorithm isn't foolproof and if the files are very different will take much longer and be more likely to suffer errors. A status window displays progress and, via the [Esc] key offers an opportunity to abort equalisation if the task is taking too long for your liking. Hints & tips Before starting equalisation use the 'First difference' [Control]+[1] option from the 'Find' menu to jump to the first line to be equalised. When equalising text files with numbered chapters/section (e.g. this file) set Égale to ignore chapter numbers in the 'Comparison mode' dialog in the 'Options' menu. --> Unregistered? Automatic line equalisation is only available to registered users. 3.6 First difference OR First identical line Select this option to jump to either the 'First difference' OR the 'First identical line' depending on the 'Search for' setting in the 'Comparison mode' dialog. 3.7 Next difference OR Next identical line Select this option to jump to either the 'Next difference' OR the 'Next identical line' depending on the 'Search for' setting in the 'Comparison mode' dialog. ____________________________________________________________________________ *****4. 'Edit' drop down menu 4.1 Undo Press the [Undo] key to reverse the last change made in the topped window: If a line has been deleted it will be re-inserted at the correct position. If a blank line has been inserted it will be deleted again. Note! If more than one line was inserted or deleted this cannot be reversed using the 'Undo' function. 4.2 Insert text line... Select this option to display the 'Insert text' dialog which features the Égale line editor. The following options are available: 'Editor:' Enter the desired text, or ASCII decimal or hex values, into the edit line. The line scrolls in real time to accommodate long lines. The character cursor can be positioned with a mouse click or scrolled using the [Left-arrow] and [Right-arrow] keys. If you also press one of the [Shift] keys the cursor will jump to the start or the end of the line respectively. 'Mode:' In decimal/hex mode multiple decimal or hex values input on one line are automatically grouped into triplets and pairs (each corresponding to one character) respectively. In binary mode, each character or decimal/hex equivalent will produce a separate line in the file. There are 3 modes according to the size of the values: - Bytes (0-255 = $00-$FF) - Words (2 Bytes each) (0-65535 = $0000-$FFFF) - Longs (4 Bytes each) (0-4294967295 = $00000000-$FFFFFFFFF) (-> all unsigned) When editing in 'word' or 'long' values, values are automatically grouped, each group representing 2 or 4 bytes. 'Insert:' [Alternate]+[I] Characters typed into the editor line are inserted at the cursor position, existing text moves along with the cursor. 'Overwrite:' [Alternate]+[W] Characters typed into the editor line overwrite any existing characters at the cursor position. You can toggle between these two options. A round filled button shows the active mode. 'Transfer:' [Alternate]+[R] With the 'Transfer' button you can copy the adjacent line from the other file to the edit line, then insert it (with or without changes) in the file you are editing. 'Display as:' 'Text:' [Alternate]+[T] Display and edit lines as text 'Decimal:' [Alternate]+[D] Display and edit ASCII values in decimal format. 'Hex:' [Alternate]+[H] Display and edit ASCII values in hex format. In hex or decimal mode the individual ASCII values of the characters are displayed, which makes it possible to enter characters not normally accessible from the keyboard. For example, enter '144' in 'Decimal' mode or '90' in 'Hex' mode, then switch to 'Text' mode and 'É' appears in the edit line. You can toggle between these three options and the text in the edit line is updated in real time. A round filled button shows the active mode. Note! In text files the input of ASCII NULL (decimal 0 or hex $00) characters is not possible. Select 'OK' to insert the text into the file at the current line cursor position or 'Cancel' to exit the dialog without making any changes. The [Shift] key If two files have been loaded, all the functions in the 'Edit' menu are sensitive as to which [Shift] key is being pressed at the time: The [Left Shift] key applies a function to the left hand file of the topped window, the [Right Shift] key applies a function to the right hand file of the topped window. Égale (in common with many other programs) precedes the filename in the window header bar with an asterisk '*' for each file which has been changed since loading (or last saving). 4.3 Edit text line... The line on which the line cursor is positioned will be displayed in the editor, where it can be edited. This option is functionally identical to 'Insert text line...' as described above, except that it modifies existing lines rather than creating new ones. In binary mode, 100 bytes are simultaneously loaded into the editor. The [Shift] key If two files have been loaded, all the functions in the 'Edit' menu are sensitive as to which [Shift] key is being pressed at the time: The [Left Shift] key applies a function to the left hand file of the topped window, the [Right Shift] key applies a function to the right hand file of the topped window. Égale shows with an asterisk in front of the filename in the mover bar of the window that the file has been altered. 4.4 Insert line It's often the case that a displacement of a single line is enough to make the entire remainder of the compared files mismatch. Using this option to insert a dummy line/s before the line on which the line cursor is positioned makes it possible to manually re-align files. Dummy lines are shown as black bars, the line numbering takes inserted lines into account. To insert 'real' text lines refer to 4.2 Insert text line... By holding down the [Control] key as well as the desired [Shift] key or while selecting the menu option, the 'Insert dummy lines' dialog is displayed. Any number of lines up to 999 can be entered but there is a pre-defined limit to the number of lines which can be inserted/deleted in each file which is set using the 'Maximum number of insertions and deletions per file' option in the 'Comparison mode' dialog from the 'Options' menu; refer to 6.1 Comparison mode... for details. The [Shift] key If two files have been loaded, all the functions in the 'Edit' menu are sensitive as to which [Shift] key is being pressed at the time: The [Left Shift] key applies a function to the left hand file of the topped window, the [Right Shift] key applies a function to the right hand file of the topped window. 4.5 Delete line The line on which the cursor is positioned can be deleted using this option; the line numbering takes deleted lines into account. The [Shift] key If two files have been loaded, all the functions in the 'Edit' menu are sensitive as to which [Shift] key is being pressed at the time: The [Left Shift] key applies a function to the left hand file of the topped window, the [Right Shift] key applies a function to the right hand file of the topped window. 4.6 Load status log... Use this option to load status log files. These will restore the displayed file to the same condition as when the status log was saved, even though the main file itself may not have altered in any way. When loading any file Égale looks in the file's directory and the main Égale path for a file with a matching name and either a '.EGA' or '.EGB' extension. If such a file is found then, provided the log file goes with the file in question, the status log will be loaded automatically (because the name and path of the associated file is saved in the log file). The [Shift] key If two files have been loaded, all the functions in the 'Edit' menu are sensitive as to which [Shift] key is being pressed at the time: The [Left Shift] key applies a function to the left hand file of the topped window, the [Right Shift] key applies a function to the right hand file of the topped window. Hints & tips With this function you can transfer additions made to a file simply to another file; just find the differences and equalise the other file by inserting blank lines. Now you can save the status, load in the target file and also load the saved status log on that side; the inserted dummy lines will be applied to the file and only have to be turned into text lines by using the 'Transfer' feature in 'Edit text line...' as often as required. 4.7 Save status... A status log file containing any inserted or deleted lines can be saved with the extension '.EGA' for a text file, or '.EGB' for a binary file. The [Shift] key If two files have been loaded, all the functions in the 'Edit' menu are sensitive as to which [Shift] key is being pressed at the time: The [Left Shift] key applies a function to the left hand file of the topped window, the [Right Shift] key applies a function to the right hand file of the topped window. Hints & tips With this function you can transfer additions made to a file simply to another file; just find the differences and equalise the other file by inserting blank lines. Now you can save the status, load in the target file and also load the saved status log on that side; the inserted dummy lines will be applied to the file and only have to be turned into text lines by using the 'Transfer' feature in 'Edit text line...' as often as required. 4.8 Clear status... If at any time you're not satisfied with the lines that you or the program has inserted or deleted you can use this option to remove them again. Note that this does NOT undo any changes you may have made using 'Insert text line...' or 'Edit text line...' . The [Shift] key If two files have been loaded, all the functions in the 'Edit' menu are sensitive as to which [Shift] key is being pressed at the time: The [Left Shift] key applies a function to the left hand file of the topped window, the [Right Shift] key applies a function to the right hand file of the topped window. ____________________________________________________________________________ *****5. 'Window' drop down menu 5.1 Cycle Select this option to change the topped window in turn, cycling through all open windows. 5.2 Help Select the 'Help' option to display the 'Main window keyboard commands' dialog or 'One-line window keyboard commands' depending on which window is currently topped. The [Help] key can be used instead. When a dialog is open the [Help] key calls up a context-sensitive help text. This is present as a so-called hypertext and to use it you need to install a suitable help system that can display it. 'ST-Guide' by Holger Weets is a very compact and easy to use example. It is freeware and is available from most well-ordered mailboxes and PD libraries. It is best to copy it in its DA form to the root directory of your boot drive and then re-set the computer. Égale needs the files EGALE.HYP and EGALE.REF and calls ST-Guide automatically. If ST-Guide is present you will find a 'HELP' button in the dialog boxes that leads to a suitable help page in the hypertext when activated. (ST-Guide is also available for 10 DM and two International Reply Coupons from Holger Weets, Tangastr. 45, D-26121 Oldenburg, Germany). 5.3 Files Beneath the Cycle and Help options the names of the files contained in the last 10 (maximum) opened windows are listed. Open windows are denoted with a tick before the menu option. Clicking on any listed entry (or pressing [Alternate]+indicated number) tops the selected window. If the window wasn't currently open it will be re-opened. ____________________________________________________________________________ *****6. 'Options' drop down menu 6.1 Comparison mode... Select this option to display the 'Comparison mode' dialog. Égale is designed to find differences or correspondences with the minimum fuss, and the global options are set using this dialog. 'Search for:' 'Correspondences:' [Alternate]+[R] Finds similarities between files. 'Differences:' [Alternate]+[D] Default. Finds differences between files. These are emphasised according to the option set in the 'Emphasis...' dialog. The following settings in this dialog take effect for all functions, i.e. also for line equalisation and functions such as 'Next difference.' 'Lines:' 'Treat as strings:' [Alternate]+[T] '... numbers:' [Alternate]+[N] If lines are treated as numbers the percentage value set in the 'Tolerance' field is used to determine whether Égale considers the numbers as equal. This option is not available in binary mode! 'Ignore:' Check boxes are provided so Égale can ignore: 'Caps=l.c:' [Alternate]+[L] Case sensitivity is not taken into account. 'Spaces:' [Alternate]+[S] Leading spaces and tabs are ignored. 'Chap.numbers:' [Alternate]+[H] Leading numbers (i.e. at the beginning of a line) are ignored. This option is handy when comparing texts with numbered paragraphs, sections, chapters etc. It's also useful when sections of text have been inserted/deleted which affect numbering. 'Editor:' [Alternate]+[E] Sets the path to an optional external text editor. Click inside the box to call the file selector, then select your desired text editor. The editor can be called and pre-loaded (the filename(s) are passed as parameters) with one or two files displayed in the topped window using the [Control]+[E] keyboard shortcut. 'Maximum insertions and deletions per file:' When Égale loads a file it reserves memory to insert/delete lines. 4 bytes are needed for each dummy line insertion and each deletion so this setting determines the amount of memory used. Égale considers the size of the loaded file to set a default value, but you can edit this value as necessary. The following alert may appear: 'Further insertion not possible, due to lack of buffer space' if you try to allocate too much memory. Important This setting only comes into effect next time Égale loads a file. --> Unregistered? Changes made to this dialog cannot be activated. You can only search for differences, and lines are always compared as strings. 6.2 Number lines Égale can also number individual lines consecutively. For this press [Alternate]+[N] or click on the 'Number lines' option in the 'Options' drop down menu. 6.3 Emphasis... Select this option to display the 'Mark target area' dialog which offers the following options: 'Off:' [Alternate]+[F] Switches emphasis off. 'Coloured:' [Alternate]+[L] Uses the colours selected in the 'Colours' dialog. 'Rest grey:' [Alternate]+[R] Default. Excluded lines are greyed out. 'Bold:' [Alternate]+[B] Included lines displayed in bold characters. 'Hide the rest:' [Alternate]+[H] Excluded lines not displayed. 'Divider only' [Alternate]+[D] The dividing-bar between excluded lines ' there:' is deleted. This makes it easy to see differences/correspondences quickly. 'Mark single' [Alternate]+[M] Characters are checked individually and 'characters:' target characters (those being searched for) are highlighted with a grey pattern so you can see precisely what's changed. Below this button is a pop-up menu which allows further options to be chosen that are only active when 'Mark single characters:' has been selected: 'First target' Highlights the first character in a line that is different (or equal); only one character is selected in each case. 'All' Égale compares each character in the two lines individually and highlights all differences/correspondences. This option is slow, especially on long lines, so only use it where you're likely to get sensible results! 'Insertions' Is the most intelligent but also the slowest setting. Égale establishes where portions of text have been added and highlights them. If correspondences are being searched for (in 'Comparison mode' dialog, see 2.2.1) the whole line except for the insertion will be highlighted. Again only use this option where you are likely to get sensible results. The algorithm used for this option is complex which takes time and requires a certain amount of intelligence from the computer. Since computers are pretty dumb Égale occasionally isn't able to display perfect results! Hints & tips The most sensible emphasis setting is probably 'Rest grey,' because you can easily see the differing or corresponding lines. However, empty lines are NOT emphasised in this mode. Turn on line numbering to easily locate empty lines. --> Unregistered? This dialog is not available. You can toggle 'Emphasis...' on (which selects the 'Rest grey' option) and off. 6.4 Display... Select this option to bring up the 'Display' dialog. The following options are available: 'Display line cursor as:' Four alternative displays are provided: 'Inverted bar' [Alternate]+[I] (default) 'Outlined bar' [Alternate]+[U] 'Small bar' [Alternate]+[M] 'Arrows' [Alternate]+[R] 'TABs:' [Alternate]+[T], then select with [Up/Down-arrow] You can choose here whether and how tab stops in text files (and spaces between the columns in binary files) are to be displayed. '(In the text below, the asterisk '*' is used in place of the ASCII 9 'clock' character of the actual dialog, since the latter does not show up in text.)' 'Off, As *' Shows each set tab stop as the ASCII 9 Tab character, with no filling. 'Fill with *' Fills the tabbed portions of lines with ASCII 9 characters. 'Fill with ' '' Fills the tabbed portions with spaces. See Examples for the effect of these options. 'Width:' Enter a value into the editable field. This number is used every time an ASCII Tab character is encountered to increment the next column position to a multiple of the value. 'Sub-division:' Text or binary files can be sub-divided into groups of lines using a faint horizontal line. Enter the desired value into the editable field. Note that 2 and 4 line divisions can also be achieved with the corresponding keys on the numerical keypad at any time without calling this dialog. With the [1], [2], [4] and [0] keys of the numerical keypad you can switch between these options without first having to call up the above dialog. Hints & tips This option is particularly suitable when viewing binary files as the line can be used to display the boundaries between words and longs. Set to '2' to display word boundaries. Set to '4' to display long boundaries. 'Info line:' [Alternate]+[I] Select the check box to display an Info line just under the GEM Window header bar. Default is off '(unchecked).' In text mode the length the line highlighted by the line cursor is shown for both files. In binary mode the character at the cursor and the following values will be evaluated and displayed: A word value 'W:' from the 2 characters or bytes starting at the cursor position), a long value 'L:' (4 characters) and a long value in hexadecimal form. This is useful for analysing file formats or during comparison to recover data values (for example, version numbers in INF files etc). --> Unregistered? This dialog is not available. The defaults apply so no Info line! 6.5 Fonts... Select this entry from the 'Options' menu to display the 'Select font' dialog. Using this dialog you can select the font and point size to be displayed in the main window from any of the available options. If GDOS (or equivalent) and a valid 'ASSIGN.SYS' is installed GDOS screen fonts can be selected. Égale does not support the use of proportional fonts. The following options are available: 'Used for:' [Alternate]+[F] A pop-up menu sets the font and point size for each of the following options (different fonts/sizes can be applied to each): 'File window(s)' 'One-line window(s)' 'Topmost window' A preview window displays a sample of the selected font and point size. 'Font:' [Alternate]+[T] A pop-up menu displays all installed fonts; select the desired font. 'Size:' [Alternate]+[S] A pop-up menu displays a choice of point sizes. The choice depends on active font selected. 6.6 Colours... Select this option to display the 'Colours' dialog. Each of the following options display a pop-up menu from which the desired colour can be selected: 'Standard:' [Alternate]+[S] Default 'Black.' Used for all lines other than those emphasised. 'Inserted line:' [Alternate]+[I] Default 'Yellow.' Used for inserted lines. In the 'Special' box: 'Emphasis:' [Alternate]+[E] Default 'Red.' Used for emphasised lines. 'Single' [Alternate]+[H] Default 'Pattern.' Used to highlight 'character:' individual characters. The pattern option is provided specifically for monochrome displays. The colours available depend on your system. At 640x200 (ST medium) you'll have 4 colours to chose from whereas on the TT or Falcon and with some graphics cards up to 16 colours will be available. Although the defaults are colours, monochrome users will not find these available for selection in the pop-ups! Important! The 'Special' options are only active if 'Coloured' is selected in the 'Mark target area' of the 'Options/Emphasis...' dialog. --> Unregistered? Because the 'Emphasis...' dialog is unavailable in the unregistered version you cannot select the 'Coloured' option so the 'Special' options are not available. 6.7 Save settings... Select this option to display the file selector which can be used to save the following settings to an .INF file: - Settings selected for each file, including search text etc. - Window and dividing-bar positions. - Names of loaded files. On starting Égale the file 'EGALE.INF' if found is loaded automatically. 6.8 Load saved settings... Select this option to display the file selector which can be used to load an .INF file. After selecting the desired .INF file a dialog appears asking whether the existing open windows should be closed before new or additional files are loaded. The following options are available: 'No:' [Alternate]+[N] or [Return] The selected INF file is not loaded. 'Yes:' [Alternate]+[Y] The existing window/s are closed and the INF file and associated files and settings are loaded. 'Additional:' [Alternate]+[A] The existing window/s remain on screen and the INF file and associated files and settings are superimposed. 6.9 Quick save and exit In addition to the normal saving of the default settings you can use this option to exit Égale and save your work and settings. This option doesn't overwrite 'EGALE.INF' but creates a second, temporary, parallel file called 'EGALE.TMP' in the same directory as 'EGALE.PRG'. Next time Égale is started 'EGALE.TMP' is read in preference to 'EGALE.INF', Égale is restored to its previous environment and 'EGALE.TMP' is deleted. ____________________________________________________________________________ *****7. Other functions 9.1 Display functions In most cases when two text files have been loaded the lines will exceed the width of the window, so you won't be able to see the entire line. By moving the dividing bar the hidden portion can be revealed. The dividing bar can be moved to any position within the window by dragging it with the mouse. Alternatively the following keyboard shortcuts also move the dividing bar: '(Use the bracket keys on the number pad)' [(] 5 characters to left. [)] 5 characters to right. [Shift]+[(] 1 character left. [Shift]+[)] 1 character right. [Control]+[(] To left margin, displays right hand file. [Control]+[)] To right margin, displays left hand file. [Esc] Toggles between left and right hand file display. [Space] Returns divider bar to its default screen centre position. Instead of moving the dividing bar it's also possible to scroll the text sideways within the text windows. The following options are available: [Left-arrow] 5 characters to left. [Right-arrow] 5 characters to right. [Shift]+[Left-arrow] 1 character to left. [Shift]+[Right-arrow] 1 character to right. [Control]+[Left-arrow] 1 screen width to left. * [Control]+[Right-arrow] 1 screen width to right. * The line cursor can be moved within the text window using the following options (the [Control] key can be used in place of the [Shift] key if prefered): [Up-arrow] 1 line up. [Down-arrow] 1 line down. [Shift]+[Up-arrow] 1 page up. [Shift]+[Down-arrow] 1 page down. [ClrHome] To start of text. [Shift]+[ClrHome] To end of (the longer) text. 9.2 Single line comparison using one-line windows A double mouse click on any line or pressing Return opens the one-line GEM window which displays the same line number from both files above one another. This means the lines are displayed the full width of the screen and is particularly useful to check exactly how the two lines differ/agree. The characters in a one-line window are always compared individually and the differences or correspondences highlighted (the options are described in more detail in the 'Emphasis...' dialog, refer to the 'Mark each character' and 'All' options in 2.2.2). In the one-line window each of the two text lines shows a double marker line starting where the line finishes and running to the right edge of the window. Thanks to this marker line you can easily establish the real length of each line, since it is easy to miss one or more spaces hanging at the end of the line and then wonder why Égale marks two apparently identical lines as 'different'. The cursor [Up-arrow] and [Down-arrow] or window up and down scroll arrows automatically perform a 'Next difference' / 'Next identical line' command. Holding down either the [Shift] or [Control] keys while pressing the cursor keys enables normal line by line scrolling. A double click in the one-line window sets the line cursor in the main window to the line clicked on in the one-line window. 9.3 Moving files Files can be dragged between Égale windows and the desktop (i.e the background) which makes it easy to compare and view any desired file(s). For example, let's consider two windows which each contain two files: Window 1 contains: A.TXT B.TXT Window 2 contains: C.TXT D.TXT Currently A.TXT is being compared with B.TXT and C.TXT is being compared with D.TXT. Let's suppose we'd like to compare A.TXT with D.TXT. To do this a 'click and drag' mouse action is used: Hold down either [Shift] key then click and hold down the left mouse button anywhere inside window 1 over B.TXT which displays an icon. Drag and release the icon over D.TXT in window 2 and Égale automatically exchanges B.TXT and D.TXT so the windows look like this: Window 1 contains: A.TXT D.TXT Window 2 contains: C.TXT B.TXT To move the files back to their original windows simply reverse the process. It's also possible to split a window comparing two files into two windows each displaying a single file. To do this drag either file onto the desktop (whilst holding down the [Shift] key). In summary: Drag a file into a two file window to exchange files. Drag a file into a single file window to move a file. Drag a file onto the desktop to create a new file window. 9.4 Quick save and exit [Shift]+[Control]+[Q] ____________________________________________________________________________ *****8. Advanced Égale features This chapter is designed to explain some of the advanced system features Égale can take advantage of. It's NOT designed for beginners, who should refer to the earlier chapters. 8.1 Passing parameters Égale can be called from a DOS type shell so long as the command line passes parameters via the desktop for Égale to evaluate. Under multitasking systems, so long as your shell supports them, you can drag two files to Égale's icon without Égale being loaded unnecessarily a second time. Input the name of the file(s) you want to load. This may contain a path: EGALE file_s.txt (if this file is to be loaded) EGALE file_a.txt file_b.txt (if these two files are to be loaded and compared). This eliminates the automatic appearance of the file selector when the program starts. Passing '-b' as an additional parameter causes Égale to load the files in binary mode: EGALE -b bugged.prg new.prg Power users may like to use wildcards, both '*' and '?' are supported. Égale will search for files that fit the entered file 'mask'. If both names have the same search pattern then the second name can be omitted. Example: EGALE erg?.dat compares the files ERGA.DAT and ERGB.DAT EGALE TEXT*.DOC compares the files TEXT_1.DOC and TEXT_21X.DOC Note: Filename/s may not start with the '*' character. The file data can also contain a path. If two files with the same name but in different folders are to be compared then you only need to input the folder for the second name. For example if: EGALE \tex\letter.tex \tex\doc\ is passed Égale compares the two files: \TEX\LETTER.TEX and \TEX\DOC\LETTER.TEX Note: For a given search pattern Égale will only find the first matching files in the relevant folder. If further files that match the pattern are present and Égale does not select the desired ones then the pattern will have to be specified more precisely. It's also possible to input a single filename fully, in which case the path is adopted from the other file, e.g.: EGALE \tex\file_a.txt file_b.txt If you only pass one file name to Égale then only this file is loaded. 8.2 Passing parameters using EGALEPAR.PRG Unfortunately the GEM desktop can't pass two arguments to a program. Start EGALEPAR.PRG instead of EGALE.PRG. EGALEPAR starts then EGALE.PRG. To pass two arguments, first drag the first file on the EGALEPAR icon then drag the second file on the EGALEPAR icon. Then EGALEPAR starts EGALE.PRG, passing both arguments. You can start EGALEPAR without parameters or passing two arguments as well. In this case EGALE.PRG is startet with these parameters. Pressing the 'Control' key while starting EGALEPAR causes the program to clean its file buffer. EGALEPAR.PRG must be in the EGALE folder! EGALEPAR is written by Werner Buthe, Frankfurt. ____________________________________________________________________________ *****9. Technical notes 9.1 Protocols supported - Égale understands VA_START. That means that under multitasking systems and/or Égale installed with Gemini, files can easily be passed to Égale. - Égale understands WM_UNTOPPED (WiNX). Provided you have WiNX installed you can perform the Cycle windows function by a short click on the title bar of the topped window. - Égale supports UFSL (Universal File SeLector) if present. - Égale supports ICFS (Iconify-Server) if present. - For passing parameters Égale understands the xARG-(ARGV)-standard. The process is also used for starting the editor. - Égale can send AV_DRAG_ON_WINDOW-messages 9.2 Known bugs With horizontal scrolling and 'Mark single characters: All ' selected in the 'Emphasis...' menu you can get disturbances with fonts whose width is not a multiple of 8 pixels due to interference from the emphasis pattern when 'Pattern' has been selected in the 'Options/Colours...' menu. This can also happen with inserted lines and is a limitation of the VDI 'NOT' Égale! 9.3 Hints & tips The menu shortcuts follow Ofir Gal's GEM-list proposals as far as practical but remain fully editable using an RSC file or file editor, such as Égale. ____________________________________________________________________________ *****10. Miscellaneous 10.1 Credits I would like to thank: - Werner Buthe, Frankfurt Germany, for his friendly support when programming some fast assembler routines and for teaching me 'correct' assembler programming by telephone. - Joe Connor, Colchester England, for editing the English documentation and undertaking distribution of the program in England. - Christof Schardt, Darmstadt Germany, for his good ideas and the original program, COMPARE. - Peter West, London England, for his hard work translating the program and documentation into English. Also thanks to the Beta testers: Rainer Albrecht, Aleks Almonacid-Lessmann, J.Jørgen von Bargen, Heinz Bokel, Robert Federle, Carsten Guthardt-Schulz, Werner Herrmann, John Mcloud, Reiner Show me Rosin, Robert Schaffner, Manfred Ssykor, Gert Stamminger, Arndt Weinmann, Ralf Zimmermann. Our thanks also to the users who, by registering, have encouraged the author to undertake further developments. - Égale is programmed in GFA Basic. Program development was aided by Ergo!pro from Columbus Soft. 10.2 Warranty and liability Whilst I will try to resolve any problems you may experience using Égale, my liability, and that of any agents I appoint, for any loss or consequential loss you may suffer due to the use of Égale is strictly limited to refunding your shareware fee. - All trademarks used are recognised and acknowledged. - All trademarks mentioned in the documentation are acknowledged and recognised. We all wish you every success using Égale.